Tools you’ll need to download before you start:

Soarer’s file set: http://geekhack.org/index.php?action=dlattach;topic=17458.0;attach=10519

HID Listen Utility (Identifies how to refer to keys while making your configuration file): https://www.pjrc.com/teensy/hid_listen.html



IMPORTANT: Plug the adapter into the keyboard FIRST, then plug the USB end into the computer.  The Soarer’s Converter may not work correctly if plugged into the computer before the keyboard is plugged into the Soarer’s Converter. 


Identifying how to name the keys while making your configuration file:

The USB HID table should be consulted to show how to name the keys that you want to configure.  If you are using a terminal keyboard with oddly marked keys or are unsure how to name a key for any reason, use the HID listen utility (linked at the top of this document). Run the HID listen utility with the keyboard and converter plugged in  and press and release the key that you want to identify.  It will output a string of letters and numbers.  Find the two digit number that has a “+” in front of it and look that number up in the HID chart in the “Codes” HTML file that is included with Soarer’s Fileset within the “docs” folder (linked at the top of the document).  You can ignore the “0x” part of the HID codes listed.  

For example, Pressing the “A” key while running HID listen will give an output of something like (which can vary depending on the keyboard protocol): 

r1C +04 d04 rF0 r1C -04 u04

The number we need is always preceded by the “+” which is “04” in this case.  Consulting the HID code set list (and ignoring the “0x” part) from Soarer’s “docs” shows that the name used for this key is simply “A” as you might expect.  

You must use exactly what the HID table shows when referring to different keys throughout the making the configuration file. HID listen is often needed for terminal keyboards that have keys that aren’t normally found on modern keyboards, so HID listen is essential for naming these keys so that they can be re-configured to something useful. 

Go to the “configs” folder and go to the file called “empty.sc” and you may rename it to “TEST” or whatever you want and drag it to the Desktop.  This will be the file that you will type your custom configuration into.  There are several other pre-made configuration files that you can examine after getting an idea of what each function does.  

Go to the desktop and open the blank configuration file that you renamed “TEST.”






Concept #1: Remapping Keys

Remapping keys changes one key to a different key:

remapblock
	LALT LGUI
	F4 MEDIA_VOLUME_DOWN
	F5 MEDIA_VOLUME_UP
	
endblock

Starts off with “remapblock” on its own line, start a new line, tab over, type the name of the key that you want to modify, put one space, then type the name of the key that you want it to be remapped (re-assigned) to.  You may name as many keys as you want in this same way underneath the “remapblock” line.  In the above example, Left ALT (LALT) will be remapped to LGUI (which is the Windows/Command/Apple key).  F4 will be set to decrease volume, and F5 will be set to increase volume.  The names of these were found in the same HID “codes” list found in the “docs” folder mentioned earlier that we used with HID listen.  When you are finished remapping keys, start a new line and type “endblock” 

SAVE YOUR CONFIGURATION FILE by going to the “file” menu and selecting “save.”




Concept #2: Uploading your configuration

Now would be a good time to upload that configuration “as-is” to see that you’ve made progress and so you’ll know how to upload later.

I am writing the configuration upload instructions assuming that you are using Windows because it is easiest to explain.  For other operating systems, you can read Soarer’s provided documentation from the fileset. 

Open “Soarer_sctools_v1.10_win32.zip” from within the “tools” folder within the original Soarer’s file set initially downloaded. 

Locate the “scaswr.bat” file within the new folder but do not click on it. Position the folder window that contains “scaswr.bat” so that you can see the “TEST” file (or whatever you named your configuration file) that is on the desktop and the “scaswr.bat” file on your computer screen.  DO NOT REMOVE the “scaswr.bat” file from the folder that it is in since it relies on the other files in that folder to function!  Drag and drop the “TEST” file into “scaswr.bat” and the configuration file will be uploaded to the Soarer’s Converter. If you see any errors in the terminal window that shows progress, then something is mistyped or missing in your “TEST” configuration file and it will tell you what line from the top that the problem is on. 

If all went well, you should be able to try out what we’ve done so far.  Pressing the Left ALT key on the keyboard that the Soarer’s converter is being used with will now be re-assigned to the Windows/Apple/Command key, F4 will decrease the computer speaker volume, and F5 will increase the speaker volume. 

From now on, you can try any of the following techniques by modifying your configuration file, saving it, and uploading the modified configuration to the Soarer’s converter by dragging the updated configuration file into “scaswr.bat” like you just did.  Please note that each time a configuration file is uploaded, it will overwrite/replace the previous configuration stored on the Soarer’s converter completely.  




Concept #3: Macros 

Macros are like a recording of a combination of keys held down or pressed in a certain order like CTRL-ALT-DELETE or outputting a string of characters like a password or website address.  Can be used to make keyboard shortcuts initiate by pressing only one key such as copy, paste, find, go to next tab, save, bold, and countless others.  

macroblock
macro ESC 
	MAKE LCTRL 
	MAKE LALT 
	MAKE DELETE
	BREAK LCTRL
	BREAK LALT 
	BREAK DELETE
endmacro
endblock

When Escape is pressed, the keyboard emulates the holding (make) of Left Control (LCTRL), Left Alt (LALT), and DELETE, then releases each one (BREAK Command for each).  So the end result is that pressing escape performs a CTRL-ALT-DELETE which would be useful for login or getting into the task manager.  The software requires that L or R be added in front of CTRL to indicate if it is the left or the right control key that is being pressed.  Does not matter for any of these examples whether right or left is used.


Usage starts with “macroblock”, new line, then “macro”, then a space, then the name of the key or key combination that you want to trigger the macro separated by spaces.  Next lines are the macro commands in the order that you want them to be followed.  New line, then “endmacro”, new line and “endblock”

Macros are also useful for common keyboard shortcuts like select all (CTRL-A) copy (CTRL-C), paste (CTRL-V), moving to the next tab (CTRL-TAB), etc. In the example below, F1 is set to Select All, F2 is set to Copy, F3 is set to Paste, and F4 is set to Next Tab.   This can be done with any other keyboard shortcut like Save, Print, Undo, etc. 

The macro SECTION of programming needs to start with “macroblock” and end with “endblock”. Each individual macro starts with “macro” and ends with “endmacro”


macroblock
macro F1
	MAKE LCTRL
	MAKE A
	BREAK LCTRL
	BREAK A
endmacro

macro F2
	MAKE LCTRL
	MAKE C
	BREAK LCTRL
	BREAK C
endmacro

macro F3
	MAKE LCTRL
	MAKE V
	BREAK LCTRL
	BREAK V
endmacro

macro F4
	MAKE LCTRL
	MAKE TAB
	BREAK LCTRL
	BREAK TAB
endmacro
endblock  

The command below shows how text can be input as macros, so you could do this for passwords or other commonly used strings of text.

Putting a “-“ in front of something on the macro line means that the key must not be pressed for the macro to trigger.  So in the example below, if you hold “T”, F6, and Left Shift, this macro will not trigger.  This is useful when you want to have similar macro enabling scenarios, but don’t want them to overlap.

macroblock
macro F6 -T LSHIFT
	PUSH_META CLEAR_META all
	Press A
	Press A
	Press A
	SET_META LSHIFT
	Delay 5
	Press A
	Press A
	Press A
	POP_ALL_META
endmacro
endblock

Above produces “aaaAAA” when pressing Left Shift and F6, but only if “T” is not pressed (because of the “-T” added)

Normal key (F6) needs to be listed before the meta, in this case meta is LSHIFT.  If all characters don’t show up in testing, do a 5 millisecond delay every so many lines.  I found that after 3 presses or after each meta set, it needs a 5 millisecond delay

Please note that the non-modifier key needs to be listed first, so in the above example, F6 needs to be listed first.  Keys like shift alt, option, and command are modifiers which Soarer will also refer to as “metas.”  





Concept #4: Function Layers


Think of the function layer like the “shift” key on a regular keyboard.  When pressed, it changes the behavior of other keys while HELD DOWN.  So numbers like 4 become symbols like $ and the normal “.” key becomes “>” while shift is held down.  

You can have up to 8 different function keys (FN’s) that can be used and each must be named first.  So in this example, FN1 is assigned to be layer “1.” 

layerblock
	FN1 1			
   	FN2 2
endblock

remapblock
    	F11 FN1
    	F12 FN2
endblock

remapblock
    	layer 1
    	Q P
	A Z
endblock

remapblock 
    	layer 2
    	Q Y
	B T
endblock


Each FN key (1 through 8) needs to be defined as an actual key that can be pressed to activate the layer, so remapblock is used for this.  In the example, “F11 Key” is assigned to FN1 which we defined as “Layer 1” on the second line “FN1 1” and “F12 Key” is assigned to be FN2 which we defined as “Layer 2.”  Pressing the F11 key causes us to move into “layer 1” which will be the same as the regular keyboard layout except for any keys that we redefine will now be different while the specified function key is held down.  So in layer 1 (activated by holding down F11), pressing Q instead produces P, but while holding down F12 (which we assigned to layer 2), pressing Q instead produces Y.  If neither function key is pressed down, Q produces Q as normal.




Concept #5 - Ifselect

If you want to toggle something on and off more permanently without needing to hold down the activating key, like remapping the ALT key to the Apple/Command/Windows key when using a Mac versus a PC, “ifselect” should be used. 

Up to 7 different ifselects are supported and must be named 1 through 7 and is formatted: SELECT_1, SELECT_2, SELECT_3, etc.

Ifselect is used by specifying what changes should be made when you press the activating key. The same key that activates it will deactivate it as well.  Any code following “ifselect” applies to that selection number until the next “ifselect” in the text document.  If you want to go back to modifying the base layer, you can put “ifselect any” meaning that it doesn’t matter what selection you are in and the code following it will always apply.


ifselect 1
remapblock
	Q P
	A Z
endblock

ifselect any
remapblock
	F10 SELECT_1
endblock


In the above example, F10 has been remapped to activate SELECT_1 which is defined above it.  The reason for this is that we always want to be able to activate or deactivate the selection no matter what selection we are in.  The code to activate it is written below and after “ifselect any” so that the converter knows that we are done defining changes for ifselect 1, which includes everything between each ifselect written in the code. 


As a final example of this, this is how you would toggle the swapping of ALT keys for the Apple/Windows key using ifselect.  We will make this the Select 2 and assign the key to activate Select 2 to be F9:

ifselect 2
remapblock 
	RALT RGUI
	LALT LGUI
endblock

ifselect any
remapblock 
	F9 SELECT_2
endblock




remapblock
	NUM_LOCK F24
	F1 SCROLL_LOCK
	F2 PAUSE
	F3 F10
	F4 F9
	F5 MEDIA_PREV_TRACK
	F6 MEDIA_PLAY_PAUSE
	F7 MEDIA_NEXT_TRACK
	F8 MEDIA_MUTE
	F9 CLEAR
	F10 UNASSIGNED
	F11 MEDIA_VOLUME_DOWN
	F12 MEDIA_VOLUME_UP
	POWER SYSTEM_POWER
endblock




